package com.tbynet.jwp.repository.spi;

import java.util.List;
import java.util.Map;

import com.tbynet.jwp.framework.core._JwpService;
import com.tbynet.jwp.model.Options;

/**
 * 选项服务接口 - 基于WordPress 4.9选项系统
 * @ClassName: OptionService
 * @Description: 负责系统选项的获取、设置和管理，遵循WordPress选项系统的设计模式
 * @Author: 佰亿互联
 * @Date: 2025年11月4日
 *
 * @Copyright: 2025 www.tbynet.com Inc. All rights reserved.
 */
public interface OptionService extends _JwpService<Options> {

    /**
     * 根据选项名获取选项
     * @param name 选项名
     * @return 选项对象
     */
    Options getOption(String name);

    /**
     * 根据选项名数组获取选项列表
     * @param names 选项名数组
     * @return 选项列表
     */
    List<Options> getOptions(String... names);

    /**
     * 设置选项值（单一职责，不处理事务）
     * @param optionName 选项名
     * @param optionValue 选项值
     * @return 设置结果
     */
    boolean setOptionValue(String optionName, String optionValue);

    // ========== 基础选项操作 ==========

    /**
     * 获取选项值（对应WordPress get_option）
     * @param optionName 选项名
     * @return 选项值，不存在时返回null
     */
    String getOptionValue(String optionName);

    /**
     * 获取选项值带默认值（对应WordPress get_option）
     * @param optionName 选项名
     * @param defaultValue 默认值
     * @return 选项值，不存在时返回默认值
     */
    String getOptionValue(String optionName, String defaultValue);

    /**
     * 设置选项值（对应WordPress update_option）
     * @param optionName 选项名
     * @param optionValue 选项值
     * @return 设置结果
     */
    boolean updateOption(String optionName, String optionValue);

    /**
     * 添加新选项（对应WordPress add_option）
     * @param optionName 选项名
     * @param optionValue 选项值
     * @return 添加结果
     */
    boolean addOption(String optionName, String optionValue);

    /**
     * 添加新选项带自动加载设置（对应WordPress add_option）
     * @param optionName 选项名
     * @param optionValue 选项值
     * @param autoload 是否自动加载
     * @return 添加结果
     */
    boolean addOption(String optionName, String optionValue, boolean autoload);

    /**
     * 删除选项（对应WordPress delete_option）
     * @param optionName 选项名
     * @return 删除结果
     */
    boolean deleteOption(String optionName);

    /**
     * 检查选项是否存在（对应WordPress get_option检查）
     * @param optionName 选项名
     * @return 是否存在
     */
    boolean optionExists(String optionName);

    // ========== 批量选项操作 ==========

    /**
     * 批量获取选项（对应WordPress get_options）
     * @param optionNames 选项名数组
     * @return 选项键值对Map
     */
    Map<String, String> getOptionsMap(String... optionNames);

    /**
     * 批量设置选项（对应WordPress update_options）
     * @param options 选项键值对
     * @return 设置结果
     */
    boolean updateOptions(Map<String, String> options);

    /**
     * 获取所有自动加载的选项（对应WordPress wp_load_alloptions）
     * @return 自动加载选项Map
     */
    Map<String, String> getAllAutoloadOptions();

    // ========== 站点信息选项 ==========

    /**
     * 获取站点URL（对应get_site_url）
     * @return 站点URL
     */
    String getSiteUrl();

    /**
     * 获取主页URL（对应get_home_url）
     * @return 主页URL
     */
    String getHomeUrl();

    /**
     * 获取博客名称（对应get_bloginfo('name')）
     * @return 博客名称
     */
    String getBlogName();

    /**
     * 获取博客描述（对应get_bloginfo('description')）
     * @return 博客描述
     */
    String getBlogDescription();

    /**
     * 获取管理员邮箱（对应get_option('admin_email')）
     * @return 管理员邮箱
     */
    String getAdminEmail();

    /**
     * 获取时区设置（对应get_option('timezone_string')）
     * @return 时区
     */
    String getTimezone();

    /**
     * 获取日期格式（对应get_option('date_format')）
     * @return 日期格式
     */
    String getDateFormat();

    /**
     * 获取时间格式（对应get_option('time_format')）
     * @return 时间格式
     */
    String getTimeFormat();

    // ========== 阅读设置选项 ==========

    /**
     * 获取每页显示文章数（对应get_option('posts_per_page')）
     * @return 每页文章数
     */
    int getPostsPerPage();

    /**
     * 获取每页RSS显示文章数（对应get_option('posts_per_rss')）
     * @return RSS每页文章数
     */
    int getPostsPerRss();

    /**
     * 获取RSS显示内容类型（全文/摘要）
     * @return 显示类型
     */
    String getRssUseExcerpt();

    /**
     * 获取首页显示类型（文章/页面）
     * @return 显示类型
     */
    String getShowOnFront();

    /**
     * 获取首页显示页面ID
     * @return 页面ID
     */
    Integer getPageOnFront();

    /**
     * 获取文章页显示页面ID
     * @return 页面ID
     */
    Integer getPageForPosts();

    // ========== 讨论设置选项 ==========

    /**
     * 获取默认评论状态（对应get_option('default_comment_status')）
     * @return 评论状态
     */
    String getDefaultCommentStatus();

    /**
     * 获取默认ping状态（对应get_option('default_ping_status')）
     * @return ping状态
     */
    String getDefaultPingStatus();

    /**
     * 是否需要评论审核（对应get_option('comment_moderation')）
     * @return 是否需要审核
     */
    boolean isCommentModeration();

    /**
     * 获取评论审核前最多链接数
     * @return 链接数
     */
    int getCommentMaxLinks();

    /**
     * 获取评论黑名单关键字
     * @return 黑名单关键字
     */
    String getCommentBlacklistKeys();

    // ========== 媒体设置选项 ==========

    /**
     * 获取缩略图大小设置
     * @return 尺寸数组 [宽度, 高度, 是否裁剪]
     */
    int[] getThumbnailSize();

    /**
     * 获取中等尺寸图片设置
     * @return 尺寸数组 [宽度, 高度]
     */
    int[] getMediumSize();

    /**
     * 获取大尺寸图片设置
     * @return 尺寸数组 [宽度, 高度]
     */
    int[] getLargeSize();

    /**
     * 获取上传文件组织方式（年月日）
     * @return 组织方式
     */
    String getUploadsUseYearmonthFolders();

    // ========== 固定链接设置选项 ==========

    /**
     * 获取固定链接结构（对应get_option('permalink_structure')）
     * @return 固定链接结构
     */
    String getPermalinkStructure();

    /**
     * 获取分类基础（对应get_option('category_base')）
     * @return 分类基础
     */
    String getCategoryBase();

    /**
     * 获取标签基础（对应get_option('tag_base')）
     * @return 标签基础
     */
    String getTagBase();

    // ========== 主题和外观选项 ==========

    /**
     * 获取当前主题（对应get_option('template')）
     * @return 当前主题
     */
    String getCurrentTheme();

    /**
     * 获取主题样式表（对应get_option('stylesheet')）
     * @return 样式表
     */
    String getStylesheet();

    /**
     * 获取主题修改时间（对应get_theme_mods）
     * @return 修改时间
     */
    long getThemeMods();

    // ========== 小工具和菜单选项 ==========

    /**
     * 获取侧边栏小工具设置
     * @return 小工具设置
     */
    String getSidebarWidgets();

    /**
     * 获取菜单设置
     * @return 菜单设置
     */
    String getNavMenuOptions();

    // ========== 用户和权限选项 ==========

    /**
     * 获取用户注册设置（对应get_option('users_can_register')）
     * @return 是否允许注册
     */
    boolean canUsersRegister();

    /**
     * 获取默认用户角色（对应get_option('default_role')）
     * @return 默认角色
     */
    String getDefaultUserRole();

    /**
     * 获取头像显示设置（对应get_option('show_avatars')）
     * @return 是否显示头像
     */
    boolean isShowAvatars();

    // ========== 置顶文章功能 ==========

    /**
     * 添加置顶文章（对应stick_post）
     * @param postId 文章ID
     * @return 添加结果
     */
    boolean addStickyPost(Object postId);

    /**
     * 移除置顶文章（对应unstick_post）
     * @param postId 文章ID
     * @return 移除结果
     */
    boolean removeStickyPost(Object postId);

    /**
     * 检查文章是否置顶（对应is_sticky）
     * @param postId 文章ID
     * @return 是否置顶
     */
    boolean isStickyPost(Object postId);

    /**
     * 获取所有置顶文章ID列表（对应get_option('sticky_posts')）
     * @return 置顶文章ID列表
     */
    List<Integer> getStickyPosts();

    // ========== 缓存和性能选项 ==========

    /**
     * 获取选项缓存版本（对应wp_cache_get('alloptions')版本控制）
     * @return 缓存版本
     */
    String getOptionCacheVersion();

    /**
     * 清除选项缓存（对应wp_cache_delete('alloptions')）
     * @return 清除结果
     */
    boolean clearOptionCache();

    /**
     * 重新加载所有自动加载选项到缓存
     * @return 加载结果
     */
    boolean reloadAutoloadOptions();

    // ========== 高级选项操作 ==========

    /**
     * 序列化选项值（对应WordPress的maybe_serialize）
     * @param value 原始值
     * @return 序列化后的值
     */
    String serializeOptionValue(Object value);

    /**
     * 反序列化选项值（对应WordPress的maybe_unserialize）
     * @param value 序列化值
     * @return 反序列化后的对象
     */
    Object unserializeOptionValue(String value);

    /**
     * 获取选项的自动加载状态
     * @param optionName 选项名
     * @return 是否自动加载
     */
    boolean isOptionAutoload(String optionName);

    /**
     * 设置选项的自动加载状态
     * @param optionName 选项名
     * @param autoload 是否自动加载
     * @return 设置结果
     */
    boolean setOptionAutoload(String optionName, boolean autoload);

    // ========== 系统维护选项 ==========

    /**
     * 获取站点维护模式状态
     * @return 是否在维护中
     */
    boolean isSiteInMaintenance();

    /**
     * 设置站点维护模式
     * @param maintenance 是否维护
     * @param message 维护消息
     * @return 设置结果
     */
    boolean setSiteMaintenance(boolean maintenance, String message);

    /**
     * 获取数据库版本（对应get_option('db_version')）
     * @return 数据库版本
     */
    String getDatabaseVersion();

    /**
     * 获取WordPress版本（对应get_bloginfo('version')）
     * @return WordPress版本
     */
    String getWordPressVersion();
}